Skip to main content

Consensus Functions

Use the Consensus adapter to manage consensus barriers.

Importing the adapter​

To use the functions of the Consensus adapter, import it as shown:
import { consensusAdapter } from 'epicenter-libs';

The consensusAdapter namespace exports functions that make calls to the Consensus API.

learn more

For descriptions of the objects used by the Consensus adapter functions, read Consensus entities.

Create​

Create barrier​

The create() function creates a new consensus barrier for a world.

Permissions​

Requires a role of PARTICIPANT or higher.

Function description​

  • Constructs a POST request to the endpoint /consensus/{worldKey}/{name}/{stage}.
  • Initializes a consensus barrier with expected roles and default actions.
  • Returns a Consensus object representing the newly created barrier.
Function signature
export async function create(
    worldKey: string,
    name: string,
    stage: string,
    expectedRoles: Record<string, number>,
    defaultActions: Record<string, Record<string, number>[]>,
    optionals: {
        ttlSeconds?: number;
        transparent?: boolean;
        allowChannel?: boolean;
    } & RoutingOptions = {}
): Promise<Consensus>

Parameters​

  • worldKey (string): World key for the world you are creating a consensus barrier in.
  • name (string): Unique string to name a set of consensus barriers.
  • stage (string): Unique string to name one stage within the set of consensus barriers.
  • expectedRoles (Record<string, number>): Identifies the set of roles expected to arrive at the barrier with the number of participants in each role.
  • defaultActions (Record<string, Record<string, number>[]>): A map of roles to the default actions for them.
  • optionals (Type: { ttlSeconds?: number; transparent?: boolean; allowChannel?: boolean } & RoutingOptions = {}): Optional routing options and barrier configuration:
    • ttlSeconds (number): The time limit for this barrier.
    • transparent (boolean): If true, all default actions are sent; if false, only one is sent.
    • allowChannel (boolean): Enables push notifications for this barrier (available for projects with phylogeny SILENT or later).

Return value​

A promise that resolves to a Consensus object representing the newly created barrier.

Usage example​

import { consensusAdapter } from 'epicenter-libs';

await consensusAdapter.create(
  '00000173078afb05b4ae4c726637167a1a9e',
  'SUBMISSIONS',
  'ROUND1',
  {
    ROLE1: 1,
    ROLE2: 1,
    ROLE3: 2,
  },
  {
    ROLE1: [{ name: 'step', arguments: [] }],
    ROLE2: [{ name: 'step', arguments: [] }],
    ROLE3: [{ name: 'step', arguments: [] }],
  },
  {
    ttlSeconds: 3600,
    transparent: true,
    allowChannel: true,
  }
);

Retrieve​

Load barrier​

Retrieves a specific consensus barrier by world key, name and stage.

Permissions​

Requires a role of PARTICIPANT or higher.

Function description​

The load() function:

  • Constructs a GET request to the endpoint /consensus/{worldKey}/{name}/{stage}.
  • Returns a Consensus object if found.
  • Returns a 204 status if the barrier exists but has no body content.
Function signature
export async function load(
    worldKey: string,
    name: string,
    stage: string,
    optionals: RoutingOptions = {}
): Promise<Consensus>

Parameters​

  • worldKey (string): World key for the world you are loading a consensus barrier from.
  • name (string): Unique string that names a set of consensus barriers.
  • stage (string): Unique string specifying which barrier to load within the set.
  • optionals (Type: RoutingOptions = {}): Optional routing options to override default behavior.

Return value​

A promise that resolves to a Consensus object if found, or returns a 204 status if successful but no content is returned.

Usage example​

import { consensusAdapter } from 'epicenter-libs';

const barrier = await consensusAdapter.load(
  '00000173078afb05b4ae4c726637167a1a9e',
  'SUBMISSIONS',
  'ROUND1'
);

List by name​

Retrieves all consensus barriers that share the specified name within the specified world.

Permissions​

Requires a role of PARTICIPANT or higher.

Function description​

The list() function:

  • Constructs a GET request to the endpoint /consensus/{worldKey}/{name}.
  • Returns all consensus barriers grouped under the specified name.
  • Returns a Consensus object if found.
  • Returns a 204 status if successful but no content is returned.
Function signature
export async function list(
    worldKey: string,
    name: string,
    optionals: RoutingOptions = {}
): Promise<Consensus>

Parameters​

  • worldKey (string): World key for the world you are retrieving consensus barriers from.
  • name (string): Unique string specifying which set of consensus barriers to retrieve.
  • optionals (Type: RoutingOptions = {}): Optional routing options to override default behavior.

Return value​

A promise that resolves to a Consensus object containing the retrieved barriers, or returns a 204 status if successful but no content is returned.

Usage example​

import { consensusAdapter } from 'epicenter-libs';

const barriers = await consensusAdapter.list(
  '00000173078afb05b4ae4c726637167a1a9e',
  'SUBMISSIONS'
);

Manage​

Update default actions​

Updates the default actions for the current participant on a transparent consensus barrier.

Permissions​

Requires a role of PARTICIPANT or higher.

Function description​

The updateDefaults() function:

  • Constructs a PATCH request to the endpoint /consensus/actions/{worldKey}/{name}/{stage}.
  • Updates the default actions originally defined in .create() for the current user.
  • Only works on barriers where transparent: true.
  • Returns a Consensus object representing the updated barrier.
Function signature
export async function updateDefaults(
    worldKey: string,
    name: string,
    stage: string,
    actions: Record<string, Record<string, number>[]>,
    optionals: RoutingOptions = {}
): Promise<Consensus>

Parameters​

  • worldKey (string): World key for the world containing the consensus barrier.
  • name (string): Unique string naming the set of consensus barriers.
  • stage (string): Unique string naming one stage of the barrier set.
  • actions (Record<string, Record<string, number>[]>): List of default actions to update for the current user.
  • optionals (Type: RoutingOptions = {}): Optional routing options to override default behavior.

Return value​

A promise that resolves to a Consensus object representing the updated barrier.

Usage example​

import { consensusAdapter } from 'epicenter-libs';

await consensusAdapter.updateDefaults(
  '00000173078afb05b4ae4c726637167a1a9e',
  'SUBMISSIONS',
  'ROUND1',
  {
    ROLE1: [{ name: 'message', value: 'DEFAULT MESSAGE 2', objectType: 'set' }]
  }
);

Submit actions​

Submits the actions for the current participant and marks them as arrived. May trigger the barrier if this is the last participant to arrive.

Permissions​

Requires a role of PARTICIPANT or higher.

Function description​

The submitActions() function:

  • Constructs a POST request to the endpoint /consensus/publish/{worldKey}/{name}/{stage}.
  • Sends the user's actions to the consensus barrier.
  • Marks the user as having arrived.
  • If transparent was set to true during creation, actions are sent directly to the model.
  • Returns a consensus response object with triggered: true for the final user to submit. This field is virtual and not stored in the database.
Function signature
export async function submitActions(
    worldKey: string,
    name: string,
    stage: string,
    actions: {
        name: string;
        arguments: string | number | Record<string, unknown>[];
    }[],
    optionals: {
        message?: string;
        ritual?: keyof typeof RITUAL;
    } & RoutingOptions = {}
): Promise<unknown>

Parameters​

  • worldKey (string): World key for the world containing the consensus barrier.
  • name (string): Unique string naming the set of consensus barriers.
  • stage (string): Unique string naming one stage of the barrier set.
  • actions ({ name: string; arguments: string | number | Record<string, unknown>[] }[]): List of action objects to submit.
  • optionals (Type: { message?: string; ritual?: keyof typeof RITUAL } & RoutingOptions = {}): Optional routing options and submission metadata:
    • message (string): Optional message stored in the barrier arrival entity.
    • ritual (keyof typeof RITUAL): Ritual identifier to associate with the submission.

Return value​

A promise that resolves to a consensus object. If this is the final submission, the response will include triggered: true.

Usage example​

import { consensusAdapter } from 'epicenter-libs';

await consensusAdapter.submitActions(
  '00000173078afb05b4ae4c726637167a1a9e',
  'SUBMISSIONS',
  'ROUND1',
  [{ name: 'step', arguments: [] }],
  { message: 'Student side submission!' }
);

Undo submission​

Removes the logged-in user from the list of participants who have arrived at a consensus barrier, allowing them to resubmit.

Permissions​

Requires a role of PARTICIPANT or higher.

Function description​

The undoSubmit() function:

  • Constructs a DELETE request to the endpoint /consensus/arrival/{worldKey}/{name}/{stage}.
  • Removes the current user’s arrival record from the specified barrier.
  • Enables the user to redo their submission.
  • Returns a Consensus object if successful.
Function signature
export async function undoSubmit(
    worldKey: string,
    name: string,
    stage: string,
    optionals: RoutingOptions = {}
): Promise<Consensus>

Parameters​

  • worldKey (string): World key for the world containing the targeted barrier.
  • name (string): Unique string naming the set of consensus barriers.
  • stage (string): Unique string specifying which barrier to undo submission for.
  • optionals (Type: RoutingOptions = {}): Optional routing options to override default behavior.

Return value​

A promise that resolves to a Consensus object if the undo operation is successful.

Usage example​

import { consensusAdapter } from 'epicenter-libs';

await consensusAdapter.undoSubmit(
  '00000173078afb05b4ae4c726637167a1a9e',
  'SUBMISSIONS',
  'ROUND1'
);

Trigger arrival for participant​

The triggerFor() function forces the arrival of a participant to a consensus barrier submitting the default actions for them. Useful for testing or making decisions for absent participants.

note

Requires facilitator-level permissions.

Permissions​

Requires a role of FACILITATOR or higher.

Function description​

  • Constructs a POST request to the endpoint /consensus/trigger/{worldKey}/{name}/{stage}.
  • Returns a generic response object.
Function signature
export async function triggerFor(
    worldKey: string,
    name: string,
    stage: string,
    userKey: string,
    actions: {
        name: string;
        arguments: string | number | Record<string, unknown>[];
    }[],
    optionals: {
        message?: string;
        ritual?: keyof typeof RITUAL;
    } & RoutingOptions = {}
): Promise<unknown>

Parameters​

  • worldKey (string): World key for the world containing the targeted barrier.
  • name (string): Unique string naming the set of consensus barriers.
  • stage (string): Unique string naming the stage of the targeted barrier.
  • userKey (string): Key of the user whose arrival is being triggered.
  • actions ({ name: string; arguments: string | number | Record<string, unknown>[] }[]): List of default actions to submit on behalf of the user.
  • optionals (Type: { message?: string; ritual?: keyof typeof RITUAL } & RoutingOptions = {}): Optional routing options and metadata:
    • message (string): Optional message describing the facilitator-triggered submission.
    • ritual (keyof typeof RITUAL): Ritual identifier to associate with the triggered arrival.

Return value​

A promise that resolves to a generic response object. The structure may vary depending on the consensus configuration.

Usage example​

import { consensusAdapter } from 'epicenter-libs';

await consensusAdapter.triggerFor(
  '00000173078afb05b4ae4c726637167a1a9e',
  'SUBMISSIONS',
  'ROUND1',
  '0000017cb60ad697e109dcb11cdd4cfcdd1d',
  [{ name: 'step', arguments: [] }],
  { message: 'Facilitator Triggered this submission!' }
);

Force close barrier​

The forceClose() function checks the timer. If time has ran out, it marks the consensus barrier as complete. Closing the barrier triggers default actions for any roles that have not arrived.

note

Requires facilitator-level permissions.

Permissions​

Requires a role of FACILITATOR or higher.

Function description​

  • Constructs a POST request to the endpoint /consensus/close/{worldKey}/{name}/{stage}.
  • Returns a 204 status if successful.
Function signature
export async function forceClose(
    worldKey: string,
    name: string,
    stage: string,
    optionals: {
        ritual?: keyof typeof RITUAL;
    } & RoutingOptions = {}
): Promise<unknown>

Parameters​

  • worldKey (string): World key for the world containing the consensus barrier to close.
  • name (string): Unique string naming the set of consensus barriers.
  • stage (string): Unique string specifying which stage of the barrier set to close.
  • optionals (Type: { ritual?: keyof typeof RITUAL } & RoutingOptions = {}): Optional routing options and ritual configuration:
    • ritual (keyof typeof RITUAL): Ritual identifier to associate with the closure event.

Return value​

A promise that resolves to unknown. Returns a 204 status if the barrier is successfully closed.

Usage example​

import { consensusAdapter } from 'epicenter-libs';

await consensusAdapter.forceClose(
  '00000173078afb05b4ae4c726637167a1a9e',
  'SUBMISSIONS',
  'ROUND1'
);

Delete​

Delete barrier​

Deletes a consensus barrier specified by a world key, name, and stage.

Permissions​

Requires a role of PARTICIPANT or higher.

Function description​

The deleteBarrier() function:

  • Constructs a DELETE request to the endpoint /consensus/{worldKey}/{name}/{stage}.
  • Returns a Consensus object if deletion is successful.
Function signature
export async function deleteBarrier(
    worldKey: string,
    name: string,
    stage: string,
    optionals: RoutingOptions = {}
): Promise<Consensus>

Parameters​

  • worldKey (string): World key for the world containing the barrier to delete.
  • name (string): Unique string naming the set of consensus barriers.
  • stage (string): Unique string specifying which barrier to delete.
  • optionals (Type: RoutingOptions = {}): Optional routing options to override default behavior.

Return value​

A promise that resolves to a Consensus object if the barrier is successfully deleted.

Usage example​

import { consensusAdapter } from 'epicenter-libs';

await consensusAdapter.deleteBarrier(
  '00000173078afb05b4ae4c726637167a1a9e',
  'SUBMISSIONS',
  'ROUND1'
);

Delete by name​

Deletes all consensus barriers with the same name in a world.

Permissions​

Requires a role of PARTICIPANT or higher.

Function description​

The deleteAll() function:

  • Constructs a DELETE request to the endpoint /consensus/{worldKey}/{name}.
  • Returns a Consensus object if deletion is successful.
Function signature
export async function deleteAll(
    worldKey: string,
    name: string,
    optionals: RoutingOptions = {}
): Promise<Consensus>

Parameters​

  • worldKey (string): World key for the world containing the barriers to delete.
  • name (string): Unique string naming the set of consensus barriers to remove.
  • optionals (Type: RoutingOptions = {}): Optional routing options to override default behavior.

Return value​

A promise that resolves to a Consensus object if the barriers are successfully deleted.

Usage example​

import { consensusAdapter } from 'epicenter-libs';

await consensusAdapter.deleteAll(
  '00000173078afb05b4ae4c726637167a1a9e',
  'SUBMISSIONS'
);